/**
 * @file param_parser.h
 * @brief 参数解析工具头文件
 * @details 本文件提供了JSON参数解析功能，用于解析入参JSON文件并生成
 *          结构化的参数传入API进行协议处理。
 * 
 *          主要功能包括：
 *          - 遥测数据参数解析
 *          - 控制命令参数解析
 *          - 状态查询参数解析
 *          - 参数验证和转换
 *          - 协议参数生成
 * 
 * @author zyb
 * @date 2025-09-28
 * @version 1.0
 * 
 * @note 本模块是参数解析工具，用于处理JSON入参
 * @warning 参数解析结果直接影响协议处理，请确保参数正确性
 */

#ifndef APP_UTILS_PARAM_PARSER_H
#define APP_UTILS_PARAM_PARSER_H

#include <stdint.h>
#include <stdbool.h>
#include <time.h>

#ifdef __cplusplus
extern "C" {
#endif

/* ==================== 错误码定义 ==================== */

/**
 * @brief 参数解析结果类型
 * @details 定义参数解析的各种结果状态
 */
typedef enum {
    PARAM_SUCCESS = 0,                    /* 解析成功 */
    PARAM_ERROR_INVALID_PARAM = -1,       /* 无效参数 */
    PARAM_ERROR_FILE_NOT_FOUND = -2,      /* 文件未找到 */
    PARAM_ERROR_FILE_READ = -3,           /* 文件读取失败 */
    PARAM_ERROR_PARSE_FAILED = -4,        /* 解析失败 */
    PARAM_ERROR_VALIDATION_FAILED = -5,   /* 验证失败 */
    PARAM_ERROR_MEMORY = -6,              /* 内存错误 */
    PARAM_ERROR_UNKNOWN = -7              /* 未知错误 */
} param_result_t;

/* ==================== 遥测数据结构 ==================== */

/**
 * @brief 遥测测量值结构
 */
typedef struct {
    char type[32];         /* 测量类型 */
    double value;          /* 测量值 */
    char unit[16];         /* 单位 */
    char quality[16];      /* 质量标志 */
} telemetry_measurement_t;

/**
 * @brief 设备状态结构
 */
typedef struct {
    bool online;                    /* 在线状态 */
    bool alarm;                     /* 告警状态 */
    bool maintenance_required;      /* 需要维护 */
} device_status_t;

/**
 * @brief 遥测数据结构
 */
typedef struct {
    char device_id[64];                    /* 设备ID */
    time_t timestamp;                      /* 时间戳 */
    telemetry_measurement_t measurements[16]; /* 测量值数组 */
    int measurement_count;                 /* 测量值数量 */
    device_status_t status;                /* 设备状态 */
} telemetry_data_t;

/**
 * @brief 协议配置结构
 */
typedef struct {
    uint16_t common_address;               /* 公共地址 */
    uint16_t information_object_address;   /* 信息对象地址 */
    uint8_t cause_of_transmission;         /* 传输原因 */
    uint8_t type_identification;           /* 类型标识 */
} protocol_config_t;

/**
 * @brief 传输配置结构
 */
typedef struct {
    char priority[16];             /* 优先级 */
    int retry_count;               /* 重试次数 */
    uint32_t timeout_ms;           /* 超时时间 */
    bool encryption;               /* 加密标志 */
} transmission_config_t;

/**
 * @brief 遥测参数结构
 */
typedef struct {
    telemetry_data_t telemetry_data;       /* 遥测数据 */
    protocol_config_t protocol_config;     /* 协议配置 */
    transmission_config_t transmission_config; /* 传输配置 */
} telemetry_params_t;

/* ==================== 控制参数结构 ==================== */

/**
 * @brief 控制参数结构
 */
typedef struct {
    double target_voltage;         /* 目标电压 */
    double target_current;         /* 目标电流 */
    char operation_mode[16];       /* 操作模式 */
    bool enable_protection;        /* 启用保护 */
} control_parameters_t;

/**
 * @brief 执行配置结构
 */
typedef struct {
    bool immediate;                /* 立即执行 */
    time_t scheduled_time;         /* 计划时间 */
    bool confirmation_required;    /* 需要确认 */
    bool rollback_on_failure;      /* 失败回滚 */
} execution_config_t;

/**
 * @brief 安全配置结构
 */
typedef struct {
    double max_voltage;            /* 最大电压 */
    double max_current;            /* 最大电流 */
    bool emergency_stop;           /* 紧急停止 */
    bool interlock_required;       /* 需要联锁 */
} safety_config_t;

/**
 * @brief 控制命令结构
 */
typedef struct {
    char command_id[64];           /* 命令ID */
    time_t timestamp;              /* 时间戳 */
    char device_id[64];            /* 设备ID */
    char command_type[32];         /* 命令类型 */
    control_parameters_t parameters; /* 控制参数 */
    execution_config_t execution_config; /* 执行配置 */
} control_command_t;

/**
 * @brief 控制参数结构
 */
typedef struct {
    control_command_t control_command;     /* 控制命令 */
    protocol_config_t protocol_config;     /* 协议配置 */
    safety_config_t safety_config;         /* 安全配置 */
} control_params_t;

/* ==================== 状态查询结构 ==================== */

/**
 * @brief 时间范围结构
 */
typedef struct {
    time_t start_time;             /* 开始时间 */
    time_t end_time;               /* 结束时间 */
} time_range_t;

/**
 * @brief 响应配置结构
 */
typedef struct {
    char format[16];               /* 格式 */
    bool include_timestamps;       /* 包含时间戳 */
    bool include_quality_flags;    /* 包含质量标志 */
    bool compression;              /* 压缩 */
} response_config_t;

/**
 * @brief 过滤配置结构
 */
typedef struct {
    time_range_t time_range;       /* 时间范围 */
    char data_types[3][16];        /* 数据类型 */
    int data_type_count;           /* 数据类型数量 */
    char quality_filter[16];       /* 质量过滤 */
} filtering_config_t;

/**
 * @brief 状态查询结构
 */
typedef struct {
    char query_id[64];             /* 查询ID */
    time_t timestamp;              /* 时间戳 */
    char device_id[64];            /* 设备ID */
    char query_type[32];           /* 查询类型 */
    char requested_data[5][32];    /* 请求数据 */
    int requested_data_count;      /* 请求数据数量 */
    response_config_t response_config; /* 响应配置 */
} status_query_t;

/**
 * @brief 状态参数结构
 */
typedef struct {
    status_query_t status_query;   /* 状态查询 */
    protocol_config_t protocol_config; /* 协议配置 */
    filtering_config_t filtering_config; /* 过滤配置 */
} status_params_t;

/* ==================== 函数声明 ==================== */

/**
 * @brief 初始化参数解析器
 * @details 初始化参数解析器模块
 * 
 * @return 初始化结果
 */
int param_parser_init(void);

/**
 * @brief 销毁参数解析器
 * @details 清理参数解析器资源
 */
void param_parser_destroy(void);

/**
 * @brief 解析遥测参数JSON文件
 * @details 从JSON文件解析遥测参数
 * 
 * @param json_file JSON文件路径
 * @param params 输出遥测参数结构
 * @return 解析结果
 */
param_result_t param_parser_parse_telemetry(const char *json_file, telemetry_params_t *params);

/**
 * @brief 解析控制参数JSON文件
 * @details 从JSON文件解析控制参数
 * 
 * @param json_file JSON文件路径
 * @param params 输出控制参数结构
 * @return 解析结果
 */
param_result_t param_parser_parse_control(const char *json_file, control_params_t *params);

/**
 * @brief 解析状态参数JSON文件
 * @details 从JSON文件解析状态参数
 * 
 * @param json_file JSON文件路径
 * @param params 输出状态参数结构
 * @return 解析结果
 */
param_result_t param_parser_parse_status(const char *json_file, status_params_t *params);

/**
 * @brief 验证遥测参数
 * @details 验证遥测参数的有效性
 * 
 * @param params 遥测参数结构
 * @return 验证结果
 */
param_result_t param_parser_validate_telemetry(const telemetry_params_t *params);

/**
 * @brief 验证控制参数
 * @details 验证控制参数的有效性
 * 
 * @param params 控制参数结构
 * @return 验证结果
 */
param_result_t param_parser_validate_control(const control_params_t *params);

/**
 * @brief 验证状态参数
 * @details 验证状态参数的有效性
 * 
 * @param params 状态参数结构
 * @return 验证结果
 */
param_result_t param_parser_validate_status(const status_params_t *params);

/**
 * @brief 获取参数解析错误信息
 * @details 获取最后一次参数解析操作的错误信息
 * 
 * @return 错误信息字符串
 */
const char* param_parser_get_error(void);

#ifdef __cplusplus
}
#endif

#endif /* APP_UTILS_PARAM_PARSER_H */
